HANDLES.HLP     Hnadles documentation

handle          ( | name --- )
        creates an array/handle for name, which holds the files
        attributes, handle number, and null terminated name.

>attrib         ( handle --- attrib-addr )
        Step to the attribute field of the handle

>hndle          ( handle --- handle-addr )
        Step to the handel storage field of the handle array.

>nam            ( handle --- name-string-addr )
        Step to the null terminated name field of the handle

FILE1           ( --- a1 )
FILE2           ( --- a1 )
        Define a couple of handles for testing

DEFEXT          ( --- a1 )
        An array holding the default extention "SEQ".

?DEF.EXT        ( --- )
        If the specified file name has no "." indicating the
        extension, then supply one from the default.

$>handle        ( filename1  handle1 --- )
        Move a counted filename1 string into handle1 for use by
        the following words.

!HCB            ( a1 | name --- )
        Get "name" from the input stream and move it into the handle a1.

FCB>HANDLE      ( a1 a2 --- )
        Copy the file name and extention from the specified FCB a1 to
        handle a2.

HANDLE>EXT      ( a1 --- a2 )
        Moves the address from the handle to the decimal point in the
        filename, if it exists.  Otherwise it steps to the null
        immediately following the filename.

$>EXT           ( a1 n1 a2 --- )
        Move the specified string a1,n1 to the extension field of the
        handle a2.

hdos1           ( cx dx fun -- ax cf | error-code 1 )
        Define a dos call assembly word, which is later used by
        HOPEN and HCREATE.

HDOS3   Yet another DOS call.
HDOS4   Still another native DOS call.

MovePointer     ( double-offset handle --- )
        Move the file pointer for handle to the position
        double-offset in the file already open in handle.

EndFile         ( handle --- double-end )
        Return the double-end pointer for the file open in
        handle, also sets the pointer to the end of the file.
        Useful for finding the end of a file, and for appending
        to the end of a file.

PATHSET         ( handle --- f1 )
        Set the current drive path into handle. returns boolean f1
        true if an error occured while performing this operation.

<HRENAME>
        Code primitive for the HRENAME function below.

hrename         ( handle1 handle2 --- return-code )
        Change the name of the file specified in handle1 to the
        name specified in handle2. Can be used to move a file
        from one directory to another on the same drive.
        Returns 18 if the rename was good, not zero.

hcreate         ( handle --- error-code )
        Create the file specified in handle, if the file already
        exists, then it is ZEROed !! Returns zero if no error
        occured.

        The file is automatically opened for read and write
        operations.

hopen           ( handle --- error-code )
        Open the file specified in handle, return error-code
        zero if the file was opened properly.

        The file is opened for both read and write operations.

rwmode          ( --- a1 )
        the variable rwmode, which defaults to a value of 2,
        controls the read write mode of the file being opened,
        the value 2 is read, or write, a value of 1 specifies
        write only, and a value of 0 specifies read only.

HCLOSE          ( handle --- f1 )
        Close the file specified by handle, return bool f1
        non-zero if an error occured.

HDELETE         ( handle --- f1 )
        Delete the file specified by handle, return bool f1
        non-zero if an error occured.

EXHREAD         ( a1 n1 handle seg1 --- n2 )
        Read from the file specified by handle to the extended segment
        area specified by seg1, a1 for length n1. Returns n2 the
        length actually read.

EXHWRITE        ( a1 n1 handle seg1 --- )
        Write from memory a1,n1 in segment seg1 to the file specified
        by handle.

HWRITE          ( a1 n1 handle --- n2 )
        Write to a file specified by a handle from a1,n1 in the code
        segment. Return n2 the length actually written.

HREAD           ( a1 n1 handle --- n2 )
        Read from a file specified by a handle to a1,n1 in the
        code segment.  Returns n2 the length actually read.

FINDFIRST       ( string --- f1 )
        Begin a search for files specified by filespec string.
        String is a null terminated un-counted string. F1 returned
        indicates whether any files matched. The found file is placed
        in the Data Transfer Area (DTA).


FINDNEXT        ( --- f1 )
        Continue the file search for a specified string. Returns
        the bool f1 true if another match was found.

SET-DTA         ( a1 --- )
        Set the Disk Transfer Area as a1.

